---
sidebar_label: Remote Relationships
sidebar_position: 15
description: Manage Remote Relationships with the Hasura Metadata API
keywords:
  - hasura
  - docs
  - Metadata API
  - API reference
  - remote joins
  - Remote Relationships
---

# Metadata API Reference: Remote Relationships

## Introduction

Remote Relationships allow you to join tables with Remote Schemas or tables on other databases.

:::tip Supported from

The Metadata API is supported for versions `v2.0.0` and above and replaces the older
[schema/metadata API](/api-reference/schema-metadata-api/index.mdx).

:::

## pg_create_remote_relationship {#metadata-pg-create-remote-relationship}

`pg_create_remote_relationship` is used to create a new remote relationship from a _Postgres table_ to an existing
Remote Schema or database.


### To Remote Schema

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
    "type":"pg_create_remote_relationship",
    "args":{
      // name of the remote relationship
      "name": "messages",
      // name of the database
      "source": "app_db",
      // name of the table in the above database on which the relationship
      // is being defined
      "table": "users",
      "definition": {
        // this remote relationship is being defined to a resolver on a
        // Remote Schema
        "to_remote_schema": {
          // name of the target Remote Schema
          "remote_schema": "forum_api",
          // the fields on the table that need to be selected to pass the
          // required data to the Remote Schema's resolver
          "lhs_fields": ["id"],
          // the join condition - this would generate this upstream request:
          // query {
          //   messages(id: id_from_users_table) { .. }
          // }
          "remote_field": {
            "messages": {
              "arguments": {
                "user_id":"$id"
              }
            }
          }
        }
      }
    }
  }
  ```

### To database

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
    "type":"pg_create_remote_relationship",
    "args":{
      // name of the remote relationship
      "name": "orders",
      // name of the database
      "source": "app_db",
      // name of the table in the above database on which the relationship
      // is being defined
      "table": "users",
        "definition": {
          "to_source": {
          // the type of the relationship, an 'object' (many-to-one) or an
          // 'array' (one-to-many)
          "relationship_type": "array",
          // the database where the target table exists
          "source": "store_db",
          // name of the table which is the target of the remote
          // relationship
          "table": "orders",
          // the join condition is specified by a mapping of columns from
          // the source's table to the target's table, i.e,
          // app_db.users.id = store_db.orders.user_id
          "field_mapping": {
            "id": "user_id"
          }
        }
      }
    }
  }
  ```

### Args syntax {#metadata-pg-create-remote-relationship-database-syntax}

| Key        | Required | Schema                                                                                      | Description                                                   |
|------------|----------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| name       | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname)             | User defined name of the new remote relationship              |
| source     | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                                     | Name of the source database of the table (default: `default`) |
| table      | true     | [TableName](/api-reference/syntax-defs.mdx#tablename)                                       | Name of the table on which the relationship is being defined  |
| definition | true     | [RemoteRelationshipDefinition](/api-reference/syntax-defs.mdx#remoterelationshipdefinition) | Definition of the remote relationship                         |

### Legacy format

Prior to `v2.0.10`, `pg_create_remote_relationship` only supported creating remote relationships to Remote Schemas and
as such it supported a different format which is now considered legacy. graphql-engine supports this legacy syntax
but we highly recommend you to migrate to the newer format.

#### Old format example

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type":"pg_create_remote_relationship",
   "args":{
      "name": "name_of_the_remote_relationship",
      "table": "users",
      "hasura_fields": ["id"],
      "remote_schema": "my-remote-schema",
      "remote_field": {
        "messages": {
           "arguments": {
              "user_id":"$id"
           }
         }
      }
   }
}
```

#### Old format args syntax {#metadata-pg-create-remote-relationship-syntax-old}

| Key           | Required | Schema                                                                                                                        | Description                                                                                                                                |
|---------------|----------|-------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| name          | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname)                                               | Name of the remote relationship                                                                                                            |
| source        | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                                                                       | Name of the source database of the table (default: `default`)                                                                              |
| table         | true     | [QualifiedTable](/api-reference/syntax-defs.mdx#tablename)                                                                    | Object with table name and schema                                                                                                          |
| hasura_fields | true     | [PGColumn](/api-reference/syntax-defs.mdx#pgcolumn) or [ComputedFieldName](/api-reference/syntax-defs.mdx#computedfieldname)  | Column/Computed field(s) in the table that is used for joining with Remote Schema field. All join keys in `remote_field` must appear here. |
| remote_schema | true     | [RemoteSchemaName](/api-reference/syntax-defs.mdx#remoteschemaname)                                                           | Name of the Remote Schema to join with                                                                                                     |
| remote_field  | true     | [RemoteField](/api-reference/syntax-defs.mdx#remotefield)                                                                     | The schema tree ending at the field in Remote Schema which needs to be joined with                                                         |

## pg_update_remote_relationship {#metadata-pg-update-remote-relationship}

`pg_update_remote_relationship` is used to update the definition of an _existing_ remote relationship defined on a
Postgres table.

### To Remote Schema

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"pg_update_remote_relationship",
     "args":{
        "name": "name_of_the_remote_relationship",
        "source": "name_of_the_source",
        "table": "users",
        // the updated definition
        "definition": {
          "to_remote_schema": {
            "remote_schema": "name_of_the_target_remote_schema",
            "lhs_fields": ["id"],
            "remote_field": {
              "messages": {
                 "arguments": {
                    "user_id":"$id"
                 }
              }
            }
        }
     }
  }
  ```

### To database

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"pg_update_remote_relationship",
     "args":{
        "name": "name_of_the_remote_relationship",
        "source": "name_of_the_source",
        "table": "users",
        // the updated definition
        "definition": {
          "to_source": {
            "relationship_type": "array",
            "source": "name_of_the_target_source",
            "table": "table_on_the_target_source"
            "field_mapping": {
              "user_id": "user_id"
            }
          }
        }
     }
  }
  ```

### Args syntax {#metadata-pg-update-remote-relationship-syntax}

| Key        | Required | Schema                                                                                      | Description                                                   |
|------------|----------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| name       | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname)             | Name of the remote relationship                               |
| source     | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                                     | Name of the source database of the table (default: `default`) |
| table      | true     | [TableName](/api-reference/syntax-defs.mdx#tablename)                                       | Name of the table on which the relationship is being defined  |
| definition | true     | [RemoteRelationshipDefinition](/api-reference/syntax-defs.mdx#remoterelationshipdefinition) | Definition of the remote relationship                         |

### Legacy format

Prior to `v2.0.10`, `pg_update_remote_relationship` only supported updating remote relationships to Remote Schemas and
as such it supported a different format which is now considered legacy. graphql-engine supports this legacy syntax
but we highly recommend you to migrate to the newer format.

#### Old format example

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "pg_update_remote_relationship",
  "args": {
     "name": "name_of_the_remote_relationship",
     "table": "users",
     "source": "name_of_the_source",
     "hasura_fields": ["id"],
     "remote_schema": "my-remote-schema",
     "remote_field": {
       "posts": {
          "arguments": {
             "user_id": "$id",
             "likes": {
                "lte":"1000"
             }
          }
       }
     }
  }
}
```

#### Old format args syntax {#metadata-pg-update-remote-relationship-syntax-old}

| Key           | Required | Schema                                                                          | Description                                                                                                                 |
|---------------|----------|---------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| name          | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname) | Name of the remote relationship                                                                                             |
| source        | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                         | Name of the source database of the table (default: `default`)                                                               |
| table         | true     | [QualifiedTable](/api-reference/syntax-defs.mdx#qualifiedtable)                 | Object with table name and schema                                                                                           |
| hasura_fields | true     | \[[PGColumn](/api-reference/syntax-defs.mdx#pgcolumn)\]                         | Column(s) in the table that is used for joining with Remote Schema field. All join keys in `remote_field` must appear here. |
| remote_schema | true     | [RemoteSchemaName](/api-reference/syntax-defs.mdx#remoteschemaname)             | Name of the Remote Schema to join with                                                                                      |
| remote_field  | true     | [RemoteField](/api-reference/syntax-defs.mdx#remotefield)                       | The schema tree ending at the field in Remote Schema which needs to be joined with.                                         |

## pg_delete_remote_relationship {#metadata-pg-delete-remote-relationship}

`pg_delete_remote_relationship` is used to delete an existing remote relationship.

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "pg_delete_remote_relationship",
    "args" : {
       "source": "name_of_the_source",
       "table": {
          "name":"users",
          "schema":"public"
       },
       "name":"name_of_the_remote_relationship"
    }
}
```

### Args syntax {#metadata-pg-delete-remote-relationship-syntax}

| Key    | Required | Schema                                                                          | Description                                                   |
|--------|----------|---------------------------------------------------------------------------------|---------------------------------------------------------------|
| source | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                         | Name of the source database of the table (default: `default`) |
| table  | true     | [TableName](/api-reference/syntax-defs.mdx#tablename)                           | Object with table name and schema                             |
| name   | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname) | Name of the remote relationship                               |

## citus_create_remote_relationship {#metadata-citus-create-remote-relationship}

`citus_create_remote_relationship` is used to create a new remote relationship on a _Citus table_ to an existing
Remote Schema or to a table on a different database.

### To Remote Schema

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"citus_create_remote_relationship",
     "args":{
        // name of the remote relationship
        "name": "messages",
        // name of the database
        "source": "app_db",
        // name of the table in the above database on which the relationship
        // is being defined
        "table": "users",
        "definition": {
          // this remote relationship is being defined to a resolver on a
          // Remote Schema
          "to_remote_schema": {
            // name of the target Remote Schema
            "remote_schema": "forum_api",
            // the fields on the table that need to be selected to pass the
            // required data to the Remote Schema's resolver
            "lhs_fields": ["id"],
            // the join condition - this would generate this upstream request:
            // query {
            //   messages(user_id: id_from_users_table) { .. }
            // }
            "remote_field": {
              "messages": {
                 "arguments": {
                    "user_id":"$id"
                 }
              }
            }
        }
     }
  }
  ```

### To database

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"citus_create_remote_relationship",
     "args":{
        // name of the remote relationship
        "name": "orders",
        // name of the database
        "source": "app_db",
        // name of the table in the above database on which the relationship
        // is being defined
        "table": "users",
        "definition": {
          "to_source": {
            // the type of the relationship, an 'object' (many-to-one) or an
            // 'array' (one-to-many)
            "relationship_type": "array",
            // the database where the target table exists
            "source": "store_db",
            // name of the table which is the target of the remote
            // relationship
            "table": "orders"
            // the join condition is specified by a mapping of columns from
            // the source's table to the target's table, i.e,
            // app_db.users.id = store_db.orders.user_id
            "field_mapping": {
              "id": "user_id"
            }
          }
        }
     }
  }
  ```

### Args syntax {#metadata-citus-create-remote-relationship-syntax}

| Key        | Required | Schema                                                                                      | Description                                                   |
|------------|----------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| name       | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname)             | Name of the remote relationship                               |
| source     | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                                     | Name of the source database of the table (default: `default`) |
| table      | true     | [TableName](/api-reference/syntax-defs.mdx#tablename)                                       | Name of the table on which the relationship is being defined  |
| definition | true     | [RemoteRelationshipDefinition](/api-reference/syntax-defs.mdx#remoterelationshipdefinition) | Definition of the remote relationship                         |

## citus_update_remote_relationship {#metadata-citus-update-remote-relationship}

`citus_update_remote_relationship` is used to update the definition of an _existing_ remote relationship defined on
a _Citus table_.

### To Remote Schema

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"citus_update_remote_relationship",
     "args":{
        "name": "name_of_the_remote_relationship",
        "source": "name_of_the_source",
        "table": "users",
        // the updated definition
        "definition": {
          "to_remote_schema": {
            "remote_schema": "name_of_the_target_remote_schema",
            "lhs_fields": ["id"],
            "remote_field": {
              "messages": {
                 "arguments": {
                    "user_id":"$id"
                 }
              }
            }
        }
     }
  }
  ```

### To database

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"citus_update_remote_relationship",
     "args":{
        "name": "name_of_the_remote_relationship",
        "source": "name_of_the_source",
        "table": "users",
        // the updated definition
        "definition": {
          "to_source": {
            "relationship_type": "array",
            "source": "name_of_the_target_source",
            "table": "table_on_the_target_source"
            "field_mapping": {
              "user_id": "user_id"
            }
          }
        }
     }
  }
  ```

### Args syntax {#metadata-citus-update-remote-relationship-syntax}

| Key        | Required | Schema                                                                                      | Description                                                   |
|------------|----------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| name       | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname)             | Name of the remote relationship                               |
| source     | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                                     | Name of the source database of the table (default: `default`) |
| table      | true     | [TableName](/api-reference/syntax-defs.mdx#tablename)                                       | Name of the table on which the relationship is being defined  |
| definition | true     | [RemoteRelationshipDefinition](/api-reference/syntax-defs.mdx#remoterelationshipdefinition) | Definition of the remote relationship                         |

## citus_delete_remote_relationship {#metadata-citus-delete-remote-relationship}

`citus_delete_remote_relationship` is used to delete an existing remote relationship.

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "citus_delete_remote_relationship",
    "args" : {
       "source": "name_of_the_source",
       "table": {
          "name":"users",
          "schema":"public"
       },
       "name":"name_of_the_remote_relationship"
    }
}
```

### Args syntax {#metadata-citus-delete-remote-relationship-syntax}

| Key    | Required | Schema                                                                          | Description                                                   |
|--------|----------|---------------------------------------------------------------------------------|---------------------------------------------------------------|
| source | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                         | Name of the source database of the table (default: `default`) |
| table  | true     | [TableName](/api-reference/syntax-defs.mdx#tablename)                           | Name of the table                                             |
| name   | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname) | Name of the remote relationship                               |

## mssql_create_remote_relationship {#metadata-mssql-create-remote-relationship}

`mssql_create_remote_relationship` is used to create a new remote relationship on an _mssql table_ to an existing
Remote Schema or to a table on a different database.

### To Remote Schema

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"mssql_create_remote_relationship",
     "args":{
        // name of the remote relationship
        "name": "messages",
        // name of the database
        "source": "app_db",
        // name of the table in the above database on which the relationship
        // is being defined
        "table": "users",
        "definition": {
          // this remote relationship is being defined to a resolver on a
          // Remote Schema
          "to_remote_schema": {
            // name of the target Remote Schema
            "remote_schema": "forum_api",
            // the fields on the table that need to be selected to pass the
            // required data to the Remote Schema's resolver
            "lhs_fields": ["id"],
            // the join condition - this would generate this upstream request:
            // query {
            //   messages(user_id: id_from_users_table) { .. }
            // }
            "remote_field": {
              "messages": {
                 "arguments": {
                    "user_id":"$id"
                 }
              }
            }
        }
     }
  }
  ```

### To database

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"mssql_create_remote_relationship",
     "args":{
        // name of the remote relationship
        "name": "orders",
        // name of the database
        "source": "app_db",
        // name of the table in the above database on which the relationship
        // is being defined
        "table": "users",
        "definition": {
          "to_source": {
            // the type of the relationship, an 'object' (many-to-one) or an
            // 'array' (one-to-many)
            "relationship_type": "array",
            // the database where the target table exists
            "source": "store_db",
            // name of the table which is the target of the remote
            // relationship
            "table": "orders"
            // the join condition is specified by a mapping of columns from
            // the source's table to the target's table, i.e,
            // app_db.users.id = store_db.orders.user_id
            "field_mapping": {
              "id": "user_id"
            }
          }
        }
     }
  }
  ```

### Args syntax {#metadata-mssql-create-remote-relationship-syntax}

| Key        | Required | Schema                                                                                      | Description                                                   |
|------------|----------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| name       | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname)             | Name of the remote relationship                               |
| source     | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                                     | Name of the source database of the table (default: `default`) |
| table      | true     | [TableName](/api-reference/syntax-defs.mdx#tablename)                                       | Name of the table on which the relationship is being defined  |
| definition | true     | [RemoteRelationshipDefinition](/api-reference/syntax-defs.mdx#remoterelationshipdefinition) | Definition of the remote relationship                         |

## mssql_update_remote_relationship {#metadata-mssql-update-remote-relationship}

`mssql_update_remote_relationship` is used to update the definition of an _existing_ remote relationship defined on
an _MS SQL table_.

### To Remote Schema

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"mssql_update_remote_relationship",
     "args":{
        "name": "name_of_the_remote_relationship",
        "source": "name_of_the_source",
        "table": "users",
        // the updated definition
        "definition": {
          "to_remote_schema": {
            "remote_schema": "name_of_the_target_remote_schema",
            "lhs_fields": ["id"],
            "remote_field": {
              "messages": {
                 "arguments": {
                    "user_id":"$id"
                 }
              }
            }
        }
     }
  }
  ```

### To database

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"mssql_update_remote_relationship",
     "args":{
        "name": "name_of_the_remote_relationship",
        "source": "name_of_the_source",
        "table": "users",
        // the updated definition
        "definition": {
          "to_source": {
            "relationship_type": "array",
            "source": "name_of_the_target_source",
            "table": "table_on_the_target_source"
            "field_mapping": {
              "id": "user_id"
            }
          }
        }
     }
  }
  ```

### Args syntax {#metadata-mssql-update-remote-relationship-syntax}

| Key        | Required | Schema                                                                                      | Description                                                   |
|------------|----------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| name       | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname)             | Name of the remote relationship                               |
| source     | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                                     | Name of the source database of the table (default: `default`) |
| table      | true     | [TableName](/api-reference/syntax-defs.mdx#tablename)                                       | Name of the table on which the relationship is being defined  |
| definition | true     | [RemoteRelationshipDefinition](/api-reference/syntax-defs.mdx#remoterelationshipdefinition) | Definition of the remote relationship                         |

## mssql_delete_remote_relationship {#metadata-mssql-delete-remote-relationship}

`mssql_delete_remote_relationship` is used to delete an existing remote relationship.

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
      "type" : "mssql_delete_remote_relationship",
      "args" : {
         "source": "name_of_the_source",
         "table": {
            "name":"users",
            "schema":"public"
         },
         "name":"name_of_the_remote_relationship"
      }
  }
  ```

### Args syntax {#metadata-mssql-delete-remote-relationship-syntax}

| Key    | Required | Schema                                                                          | Description                                                   |
|--------|----------|---------------------------------------------------------------------------------|---------------------------------------------------------------|
| source | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                         | Name of the source database of the table (default: `default`) |
| table  | true     | [TableName](/api-reference/syntax-defs.mdx#tablename)                           | Name of the table on which the relationship is being defined  |
| name   | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname) | Name of the remote relationship                               |

## bigquery_create_remote_relationship {#metadata-bigquery-create-remote-relationship}

`bigquery_create_remote_relationship` is used to create a new remote relationship on a _BigQuery table_ to an
existing Remote Schema or to a table on a different database.

### To Remote Schema

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"bigquery_create_remote_relationship",
     "args":{
        // name of the remote relationship
        "name": "messages",
        // name of the database
        "source": "app_db",
        // name of the table in the above database on which the relationship
        // is being defined
        "table": {
           "dataset": "<source_dataset_name>",
           "name": "users"
        },
        "definition": {
          // this remote relationship is being defined to a resolver on a
          // Remote Schema
          "to_remote_schema": {
            // name of the target Remote Schema
            "remote_schema": "forum_api",
            // the fields on the table that need to be selected to pass the
            // required data to the Remote Schema's resolver
            "lhs_fields": ["id"],
            // the join condition - this would generate this upstream request:
            // query {
            //   messages(user_id: id_from_users_table) { .. }
            // }
            "remote_field": {
              "messages": {
                 "arguments": {
                    "user_id":"$id"
                 }
              }
            }
        }
     }
  }
  ```

### To database

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
    "type": "bigquery_create_remote_relationship",
    "args": {
      // name of the remote relationship
      "name": "orders",
      // name of the database
      "source": "app_db",
      // name of the table in the above database on which the relationship
      // is being defined
      "table": {
          "dataset": "<source_dataset_name>",
          "name": "users"
      },
      "definition": {
        "to_source": {
          // the type of the relationship, an 'object' (many-to-one) or an
          // 'array' (one-to-many)
          "relationship_type": "array",
          // the database where the target table exists
          "source": "store_db",
          // name of the table which is the target of the remote
          // relationship
          "table": {
              "name": "orders",
              "dataset": "<target_dataset_name>"
          },
          // the join condition is specified by a mapping of columns from
          // the source's table to the target's table, i.e,
          // app_db.users.id = store_db.orders.user_id
          "field_mapping": {
            "id": "user_id"
          }
        }
      }
    }
  }
  ```

### Args syntax {#metadata-bigquery-create-remote-relationship-syntax}

| Key        | Required | Schema                                                                                      | Description                                                   |
|------------|----------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| name       | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname)             | Name of the remote relationship                               |
| source     | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                                     | Name of the source database of the table (default: `default`) |
| table      | true     | [BigQueryTableName](/api-reference/syntax-defs.mdx#bigquerytablename)                       | Name of the table on which the relationship is being defined  |
| definition | true     | [RemoteRelationshipDefinition](/api-reference/syntax-defs.mdx#remoterelationshipdefinition) | Definition of the remote relationship                         |

## bigquery_update_remote_relationship {#metadata-bigquery-update-remote-relationship}

`bigquery_update_remote_relationship` is used to update the definition of an _existing_ remote relationship defined
on a _BigQuery table_.

### To Remote Schema

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"bigquery_update_remote_relationship",
     "args":{
        "name": "name_of_the_remote_relationship",
        "source": "name_of_the_source",
        "table": "users",
        // the updated definition
        "definition": {
          "to_remote_schema": {
            "remote_schema": "name_of_the_target_remote_schema",
            "lhs_fields": ["id"],
            "remote_field": {
              "messages": {
                 "arguments": {
                    "user_id":"$id"
                 }
              }
            }
        }
     }
  }
  ```

### To database

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"bigquery_update_remote_relationship",
     "args":{
        "name": "name_of_the_remote_relationship",
        "source": "name_of_the_source",
        "table": "users",
        // the updated definition
        "definition": {
          "to_source": {
            "relationship_type": "array",
            "source": "name_of_the_target_source",
            "table": "table_on_the_target_source"
            "field_mapping": {
              "user_id": "user_id"
            }
          }
        }
     }
  }
  ```

### Args syntax {#metadata-bigquery-update-remote-relationship-syntax}

| Key        | Required | Schema                                                                                      | Description                                                   |
|------------|----------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| name       | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname)             | Name of the remote relationship                               |
| source     | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                                     | Name of the source database of the table (default: `default`) |
| table      | true     | [BigQueryTableName](/api-reference/syntax-defs.mdx#bigquerytablename)                       | Name of the table on which the relationship is being defined  |
| definition | true     | [RemoteRelationshipDefinition](/api-reference/syntax-defs.mdx#remoterelationshipdefinition) | Definition of the remote relationship                         |

## bigquery_delete_remote_relationship {#metadata-bigquery-delete-remote-relationship}

`bigquery_delete_remote_relationship` is used to delete an existing remote relationship.

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "bigquery_delete_remote_relationship",
    "args" : {
       "source": "name_of_the_source",
       "table": {
          "name":"users",
          "dataset":"some_dataset_name"
       },
       "name":"name_of_the_remote_relationship"
    }
}
```

### Args syntax {#metadata-bigquery-delete-remote-relationship-syntax}

| Key    | Required | Schema                                                                          | Description                                                   |
|--------|----------|---------------------------------------------------------------------------------|---------------------------------------------------------------|
| source | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                         | Name of the source database of the table (default: `default`) |
| table  | true     | [BigQueryTableName](/api-reference/syntax-defs.mdx#bigquerytablename)           | Name of the table on which the relationship is being defined  |
| name   | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname) | Name of the remote relationship                               |

## create_remote_schema_remote_relationship {#metadata-create-remote-schema-remote-relationship}

`create_remote_schema_remote_relationship` is used to create a new remote relationship on a Remote Schema's type to
a table on a database or to another Remote Schema.

:::info Supported types

Currently only [object types](https://spec.graphql.org/October2021/#sec-Objects) on a Remote Schema are supported.

:::

### To Remote Schema

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"create_remote_schema_remote_relationship",
     "args":{
        // name of the remote relationship
        "name": "messages",
        // name of the Remote Schema
        "remote_schema": "users_api",
        // the object type in the above Remote Schema on which the
        // relationship is being defined
        "type": "user",
        "definition": {
          // this remote relationship is being defined to a resolver on a
          // Remote Schema
          "to_remote_schema": {
            // name of the target Remote Schema
            "remote_schema": "forum_api",
            // the fields on the table that need to be selected to pass the
            // required data to the Remote Schema's resolver
            "lhs_fields": ["id"],
            // the join condition - this would generate this upstream request:
            // query {
            //   messages(user_id: id_from_user_type) { .. }
            // }
            "remote_field": {
              "messages": {
                 "arguments": {
                    "user_id":"$id"
                 }
              }
            }
        }
     }
  }
  ```

### To database

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"create_remote_schema_remote_relationship",
     "args":{
        // name of the remote relationship
        "name": "messages",
        // name of the Remote Schema
        "remote_schema": "users_api",
        // the object type in the above Remote Schema on which the
        // relationship is being defined
        "type": "user",
        // name of the remote relationship
        "definition": {
          "to_source": {
            // the type of the relationship, an 'object' (many-to-one) or an
            // 'array' (one-to-many)
            "relationship_type": "array",
            // the database where the target table exists
            "source": "store_db",
            // name of the table which is the target of the remote
            // relationship
            "table": "orders"
            // the join condition is specified by a mapping of columns from
            // the Remote Schema's type to the target's table, i.e,
            // users_api.user.id = store_db.orders.user_id
            "field_mapping": {
              "id": "user_id"
            }
          }
        }
     }
  }
  ```

### Args syntax {#metadata-create-remote-schema-remote-relationship-syntax}

| Key           | Required | Schema                                                                                      | Description                                                 |
|---------------|----------|---------------------------------------------------------------------------------------------|-------------------------------------------------------------|
| name          | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname)             | Name of the remote relationship                             |
| remote_schema | true     | [RemoteSchemaName](/api-reference/syntax-defs.mdx#remoteschemaname)                         | Name of the Remote Schema                                   |
| type          | true     | [GraphQLName](/api-reference/syntax-defs.mdx#graphqlname)                                   | Name of the type on which the relationship is being defined |
| definition    | true     | [RemoteRelationshipDefinition](/api-reference/syntax-defs.mdx#remoterelationshipdefinition) | Definition of the remote relationship                       |

## update_remote_schema_remote_relationship {#metadata-update-remote-schema-remote-relationship}

`update_remote_schema_remote_relationship` is used to update an existing remote
relationship defined on a Remote Schema's type.

### To Remote Schema

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"update_remote_schema_remote_relationship",
     "args":{
        "name": "messages",
        "remote_schema": "users_api",
        "type": "user",
        // new definition of the remote relationship
        "definition": {
          "to_remote_schema": {
            "remote_schema": "forum_api",
            "lhs_fields": ["id"],
            "remote_field": {
              "messages": {
                 "arguments": {
                    "user_id":"$id"
                 }
              }
            }
        }
     }
  }
  ```

### To database

  ```http
  POST /v1/metadata HTTP/1.1
  Content-Type: application/json
  X-Hasura-Role: admin

  {
     "type":"update_remote_schema_remote_relationship",
     "args":{
        "name": "messages",
        "remote_schema": "users_api",
        "type": "user",
        // new definition of the remote relationship
        "definition": {
          "to_source": {
            "relationship_type": "array",
            "source": "store_db",
            "table": "orders"
            "field_mapping": {
              "id": "user_id"
            }
          }
        }
     }
  }
  ```

### Args syntax {#metadata-update-remote-schema-remote-relationship-syntax}

| Key           | Required | Schema                                                                                      | Description                                                 |
|---------------|----------|---------------------------------------------------------------------------------------------|-------------------------------------------------------------|
| name          | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname)             | Name of the remote relationship                             |
| remote_schema | true     | [RemoteSchemaName](/api-reference/syntax-defs.mdx#remoteschemaname)                         | Name of the Remote Schema                                   |
| type          | true     | [GraphQLName](/api-reference/syntax-defs.mdx#graphqlname)                                   | Name of the type on which the relationship is being defined |
| definition    | true     | [RemoteRelationshipDefinition](/api-reference/syntax-defs.mdx#remoterelationshipdefinition) | Definition of the remote relationship                       |

## delete_remote_schema_remote_relationship {#metadata-delete-remote-schema-remote-relationship}

`delete_remote_schema_remote_relationship` is used to delete an existing remote relationship defined on a Remote
Schema's type.

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type":"delete_remote_schema_remote_relationship",
   "args":{
      "name": "messages",
      "remote_schema": "users_api",
      "type": "user"
   }
}
```

### Args syntax {#metadata-delete-remote-schema-remote-relationship-syntax}

| Key           | Required | Schema                                                                          | Description                                                 |
|---------------|----------|---------------------------------------------------------------------------------|-------------------------------------------------------------|
| name          | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname) | Name of the remote relationship                             |
| remote_schema | true     | [RemoteSchemaName](/api-reference/syntax-defs.mdx#remoteschemaname)             | Name of the Remote Schema                                   |
| type          | true     | [GraphQLName](/api-reference/syntax-defs.mdx#graphqlname)                       | Name of the type on which the relationship is being defined |
